The following sections describe how to set up a development environment, how to contribute your code and what are our contribution standards.
Install NLP Architect from source (Github) and install supplemental development packages:
pip3 install -r dev-requirements.txt
- File an issue (to track your contribution):
- Create an issue on GitHub: https://github.com/NervanaSystems/nlp-architect/issues
- Clone and/or update your checked out copy of nlp-architect to ensure you have the most recent commits from the master branch:
git clone https://github.com/NervanaSystems/nlp-architect.git cd nlp-architect git fetch origin git checkout master git pull
- Create a new feature branch for your work and switch to it. Give it a meaningful name related to the task(s) at hand:
git checkout -b my_new_feature_branch
- Ideally you’d start by creating one or more unit tests with the functionality you expect your new feature to perform. These should reside under the appropriate tests subdirectory of whatever you are changing. Then hack away at the code until you feel your feature is complete. Once satisfied, run the code through the following checks:
nlp_architect test # ensure all are OK nlp_architect style # ensure there are no style related issues
- If necessary you may want to update and/or rebuild the documentation. This all exists under doc/source and is in Sphinx reStructuredText format:
nlp_architect doc # builds the doc and starts a local server directly
- Commit your changes and push your feature branch to your GitHub fork. Be sure to add a descriptive message and reference the GitHub issue associated with your task (ex. #1). You will also want to rebase your commits down to a single sensible commit to make things clean for the merge process:
git add my_updated_files git commit -m "Added new awesome functionality. Closes issue #1" git push origin my_new_feature_branch
- Create a new pull request to get your feature branch merged into master for others to use. You’ll first need to ensure your feature branch contains the latest changes from master. Furthermore, internal devs will need to assign the request to someone else for a code review. You must also ensure there are no errors when run through the items defined in step 4.
# (external contribs): make a new pull request: https://github.com/NervanaSystems/nlp-architect/pulls # merge latest master changes into your feature branch git fetch origin git checkout master git pull origin master git checkout my_new_feature_branch git merge master # you may need to manually resolve any merge conflicts
- If there are issues you can continue to push commits to your feature branch by following step 6. They will automatically be added to this same merge request.
- Once your change has been successfully merged, you can remove the source branch and ensure your local copy is up to date:
git fetch origin git checkout master git pull git branch -d my_new_feature_branch git branch -d -r origin/my_new_feature_branch
- Give yourself a high five for a job well done!
To ensure consistency across developers, we enforce the following conventions on all of the code in neon (which is primarily python plus some reStructuredText for documentation).
- By and large we conform to PEP8 with the following exceptions:
- Maximum line length is 99 characters
- All public class and function names must have docstrings, and these docstrings must conform to Google Style Docstrings as our API documentation is auto-generated from these. To do this we utilize the Napoleon Sphinx extensions.
- Documents are created using reStructuredText.
- Limit your docs to 2-3 levels of headings.
- New .rst files will show up in the sidebar, and any first and second level headings will also show up in the menu. Keep the sidebar short and only add essentials items there. Otherwise, add your documentation to the pre-existing files. You can add to the toctree manually, but please don’t add or create pages unless absolutely necessary!
- If you created a new class, add it to the API by creating a new section in api.rst and create an autosummary. Anytime you add an autosummary, please remember to add :nosignatures: to keep things consistent with the rest of our docs.
- Every time you make a significant contribution, add a short description of it in the relevant document.
To ensure code stability, developers are required to write tests for contributed modules, according to these guidelines:
- Tests are written using pytest
- All test functions must have docstrings
- Tests modules should be placed in the ./tests directory
- Regression tests – check that claimed model/pipeline end-to-end functionality is preserved after changes. Test sub-components where appropriate.
- Util tests – test functionality of utility modules.
- Framework tests – test http service input/output
Before creating a pull request, ensure that your test pass. To a test module, issue the following command: